Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 017 / batcom.dqc / BATCOM.DOC

Wrap

Text File | 1984-05-17 | 25.4 KB | 783 lines

BAT.COM - FUNCTIONS ------------------- QUICK REFERENCE: --------------- Batch file commands [operands] Batch file statement: BEEP [stmt] BAT -[lbl] [cmd] | [cmd] BEGSTACK...[text] [\hex] [;]... END BEGTYPE ...[text] [\hex] [;]... END Control Functions: CALL -[lbl] STACK.ON CLS [stmt] STACK.OFF EXIT [stmt] -stopbatch,ret to DOS STACK.PURGE GOTO -[lbl] TRACE.ON IF [token] < = > <> [token] [stmt] TRACE.OFF INKEY [text] [var] READ [text] [vars] Variables: READSCRN [vars] %0 to %9 - DOS Vars RETURN %A to %O - Global Vars SKIP [numoflines] %Q - Stack status(S or K) STATEOF [filename].or.[var] %R - Return Code [0:4FE] STACK ...[tokens] [;]... %S - Space Literal TYPE ...[tokens] [;]... %V - Default Drive [var] = [token] + - * / # $ [token] %% - "%" Literal | delimits multiple commands on a line * [comment] NOTES: 1) Standard DOS commands can be intermixed freely with BAT commands. 2) Like basic, things at the top are quick for goto's / loops to find. 3) A skip is faster than a goto, but can only move down the bat file. 4) Up to 15 chars are allowed for labels, contents of vars, and literals 5) 10 variables are provided to be passed to/from DOS. They're %0 to %9. 6) 15 variables are provided for user use only. They're %A to %O. 7) The variable %R is a return code that any routine can set at [0:04FE] 8) 'BEGTYPE' & 'BEGSTACK' do not do variable substitution. 9) BEGTYPE command can have screen attributes via a '\hex' format. 10) BEGSTACK command can have timing attributes via a '\hex' format. 11) Spaces are needed to delimit operators. 12) Non-spaces will concatenate variables and literals. 13) STATEOF sets %R (return code) as the state of existence of a file. DETAILED DESCRIPTION -------------------- TYPE command: Prints text and contents of variables on display. ------------ example: BAT TYPE HELLO THERE You can also put DOS variables into this command to display their contents. For example, if the "TRIAL.BAT" file contained the line: BAT TYPE HELLO THERE %1 %2 Then when we start the BAT program from DOS, we might enter: TRIAL COMPUTER USER * COMPUTER ==> %1, USER ==> %2 DOS will automatically store the words after the program name into its variables. Therefore, in the TYPE command, we will see contents of these variables on the screen. The resulting message would be: HELLO THERE COMPUTER USER If the %4 variable contains the word DAY, the command to display the words FUN DAY on the display is: BAT TYPE FUN %4. BEGTYPE command: a second method of putting text onto the display. --------------- Although it will not display the contents of variables, it is very useful for displaying large blocks of text, such as menus. For example, if the "TRIAL.BAT" file contains: BAT BEGTYPE This is a large block of text. It is useful for menus. Note that Upper/Lower case characters are displayed intact here. The block is always ended with "END" in the first column after the text finishes. END When executed, the "TRIAL.BAT" program will display: This is a large block of text. It is useful for menus. Note that Upper/Lower case characters are displayed intact here. The begtype command can also highlight text by using the form: [\hex] For example, if the text block contained \0f within the text, the result would be High Intensity Text. By choosing different values, the screen attributes can be controlled to create inverted video, blinking, underlined, and very colorful text. BEGTYPE display control example: bat begtype \04Normal Red on Black \07 \0fHigh Intensity High Intensity\07 \21Underlined Blue on Green \07 \85Flashing Normal Flashing Magenta on Black\07 And \0fmany\07 other combinations! \1b[33;44m Users of DOS 2.0 ANSI.SYS can also control the display. \1b[0m end bat begtype <\0FS\07>ystem <\0FD\07>emo <\0FH\07>elp end \0F causes a change to high intensity for the characters that follow within a begtype command, while \07 restores all following to normal intensity. CLS command: used to clear the display before printing data. ----------- "BAT CLS BEGTYPE" is useful for printing menus and text to the screen. READ command: reads 1 input line, typed from the keyboard or the stack. ------------ When the command word READ is seen in the batch file, an input line is accepted from the user. All function keys are assigned to the normal DOS edit functions. When ENTER is pressed, the input line is assigned to *DOS* variables. Each word will be assigned in order to the variables indicated after the READ command. When there are no more variables after the READ command to assign, the remainder of the response is thrown away. If there are more variables to be assigned after the READ command than there are words from the user, these variables will be cleared out to a empty state. For example: BAT READ Please enter your name ==> %1 %2 This would prompt the user and wait for him to enter two words. These words will be saved in the %1 and %2 variables. Note that there does not have to be any variables indicated after the command READ. In this case, BAT would wait for the enter key, throw away any response, then continue to process the next batch file command. INKEY command: gets a single keystroke from the keyboard or stack. ------------- This command will wait for the user to enter a single key on the keyboard and return its value in the optional variable. This key can be not only letters, but all function keys, control keys, etc. For example: BAT INKEY Press any key to continue... %0 When the user presses a single key, that key is saved into the variable %0. If the key that is pressed is in the range of "!" to "z" (decimal 33 to 122) then the key is saved to the optional variable. ** If you wish this key to be echoed to the display, you must specifically use the TYPE command. If the key is NOT in the above range, then the key will be converted to the form "KEYxxx" where xxx is the hex value of the key. Extended key codes will be in the range KEY100 to KEY1FF and nonextended key codes will be in the range KEY000 to KEY0FF. Refer to Appendix G of the Basic manual for a complete description of the various assignments of key codes. The character does not have to be assigned to a variable. If the variable name is not present following the command INKEY, the system will wait for any key to be pressed from the user, and then continue processing. PROGRAM CONTROL: GOTO, CALL, RETURN, and IF commands ------------------------------------------------------ GOTO command: ------------ BAT GOTO -LABEL If this line is put into a ".BAT" file, then it will stop execution at this line and resume at the line within the file which contains: BAT -LABEL This is a unconditional branch. If the label is not present within the file, an error will result. Note the minus (-) sign before the label name. Labels must be preceded with a minus sign. CALL command: ------------ The line where the CALL command is encountered is saved, then a branch to a label is done, as with the GOTO command. However, only THREE lines can be saved away, at a time, with this command. When a RETURN command is found, the last line that was saved is restored. Execution resumes at the line following the original CALL command. For example, if a program contains: BAT TYPE One BAT CALL -LABEL BAT CALL -LABEL BAT TYPE Four BAT EXIT BAT -LABEL BAT TYPE Two BAT TYPE Three BAT \07RETURN\07 You will see on the display: ONE TWO THREE TWO THREE FOUR IF command: ---------- The general form of this command is: BAT IF _word _condition _word _operation Each _word can be a fixed string of letters, or a variable, or a combination of each. _condition can be: < less than = equal to > greater than <> not equal to _operation can be any of the Extended Batch Language commands. For example, all of the following IF statements will compare correctly and execute their corresponding TYPE command. The first two statements will initialize variables used in the IF commands. BAT %1 = ABC BAT %2 = BAT IF ABC = %1 TYPE The variable contains ABC. BAT IF %1 = abc TYPE This also matches. BAT IF 0 <> 00 TYPE These are different lengths. BAT IF 0 < 00 TYPE 0 has a smaller length. BAT IF 456 > 123 TYPE Numerically, 456 is bigger. BAT IF 456 < %1 TYPE ASCII value of 456 is smaller. BAT IF AABCD = A%1D TYPE Token substitutions are made. BAT IF %2 <> %1 TYPE Variables are different lengths. BAT IF .%2 = . TYPE This matches if var is empty. BAT IF BOX = BOX IF DOG <> CAT TYPE Did multi-if compare. Another, bat inkey %k bat if %k = KEY003 goto -opt0 |* Break key bat if %k = KEY01B %L = 0 | return |* ESC key bat if %k = KEY147 %L = 0 | return |* Home key bat if %k = KEY149 %L = %L - 1 | cls | return |* PgUp key bat if %k = KEY151 %L = %L + 1 | cls | return |* PgDn key bat if .%a <> . skip 8 |* end of string ? bat read Press the ─┘ key to continue to next section..... bat return bat %b = %a $ 1 1 |* get 1st letter bat %a = %a $ 2 |* remove it from string bat inkey %i |* get a key. bat if %i = KEY020 type %b; | goto -tryit.loop bat if %i = %b type %i; | goto -tryit.loop bat beep goto -tryit.try more if's, etc.... bat read Enter the number of your selection. > %A bat if / = /%a %a = 1 bat if %a < 13 if %a > 1/ cls goto -opt%a bat if %a < : if %a > / cls goto -opt%a bat beep begtype I DON'T KNOW THAT OPTION! Just enter a number 0 to 12 and press the ─┘ key. end bat begtype <\0FS\07>ystem <\0FD\07>emo <\0FH\07>elp *prompt for next test end bat -exiting inkey %a *read kybd bat if %a = S exit *stop batch,ret DOS bat if %a = H goto -line0 *jmp to start bat if %a = D stack BATDEMO | exit *put a command on bat *the stack,& exit bat beep goto -exiting *if's failed KEYBOARD STACK.... There is a method within the BAT language for answering questions from programs without operator intervention. This is done by a "keyboard stack". By entering data into the stack, you will essentially be entering data through your keyboard when any program requests it. In this way, a batch file can now answer questions programs may have by 'typing' them for the user. The keyboard stack operates in a "first-in first-out" basis. That is, the first line of text put into the stack will be the first seen by the program when it reads the keyboard. The second line entered will be the second seen by the program, and so on. As long as there is text remaining on the stack, ALL requests for data from the keyboard will actually come from the stack. Once the stack has been emptied by the program, data will then come from the keyboard as usual. STACK command: ------------- It will "push" data into the keyboard stack area. When any program is ready to accept information from the keyboard, the parameters after the STACK command will be used as input. For example: BAT * This program will issue remarks to DOS. BAT %1 = HELLO BAT STACK REM THIS IS A REMARK FOR DOS BAT STACK REM VARIABLE %%1 = %1 When executed, the following will appear on the screen: A>REM THIS IS A REMARK FOR DOS A>REM VARIABLE %1 = HELLO BEGSTACK command: used to dump large amounts of data to the stack area. ----------------- Although no parameter substitution is performed, there are several advantages to its use. 1) If a line ends with the ";" (semicolon) character, a carriage return will NOT be stacked. 2) If "\HEX" is used (HEX is a number from 01 to FE) then this exact keyboard value will be stacked. This is useful for stacking special control characters and symbols. 3) If "\00\HEX" is used, an EXTENDED key code will be stacked. This is useful for stacking FUNCTION keys and the like. Refer to the Basic manual in Appendix G under "Extended Codes". 4) If \FF\HEX is used, the stack will delay the keyboard characters from appearing to the program for HEX number of CPU "ticks". There are about 12 hex (18 decimal) ticks per second in the CPU. In all cases, the word HEX above represents a two digit hexadecimal number. Finally, \\ can be used to stack a single backslash. An example of a BEGSTACK command:: BAT BEGSTACK \09 * Will stack the tab key. This text will be stacked ; on one line! \00\3B * Will stack an F1 key. \\ * Is seen as one backslash. \FF\24 * Will pause two seconds. end another... bat begstack This text is actually being typed for you from the keyboard stack. All keys, including control keys and function keys can come from the stack. Keystrokes can \ff\10even \ff\10have \ff\10delayed \ff\10typing. \1a end rem ... Below is the DOS command that will read the keyboard stack. copy con: nul: bat *returning from DOS command* Hint: Some programs remove keystrokes before accepting a critical key. In some cases this can be avoided by using \FF\01 in the BEGSTACK command. There are also three control commands which are associated with the stack: STACK.OFF - Redirects data to come directly from the physical keyboard. Does not remove any data in the stack. STACK.ON - Directs data to come from the stack. This is the default. STACK.PURGE - Removes any data from the stack and keyboard buffers which are pending. The size of the keyboard stack defaults to 512 bytes. This value can be changed by making the FIRST STATEMENT which is executed by the Extended Batch Language program be of the form: "BAT * size". Size is the decimal number of bytes to reserve for the stack. This must be executed, for instance, when a system reset is performed because once this area is installed, the size is never altered until another system reset. READSCRN command: ---------------- A line of text is read from the display screen into variables. Having the ability to read text from the display can be useful for determining the result of another program, or making a query for some system status which would not normally be available within a batch file. For example, by reading a DIRECTORY from the screen, a series of files can be submitted to the macro assembler. Once the assembly is completed, the status can be read from the screen to determine if there were errors which would stop the link step. Virtually any message which a program can generate can be used as feedback to a batch file by using READSCRN. Its operation is very much like the READ command except for the fact that the information which is being read is coming from the display screen and not the keyboard. Like the READ command, the text from the screen is tokenized (separated at word boundaries and assigned to variables). The return code %R will be reflect the line number on the display that was read. This number will be in the range of 1 to 25 for the top to bottom lines respectively. Once a line is read, this command will be set to read the PREVIOUS line. Repeated "readscrn" commands will read *> UP <* the display!!! A READSCRN example: BAT CLS BAT TYPE HELLO THERE BAT READSCRN %A %B %C After execution: %A contains HELLO %B contains THERE %C contains nothing, it is empty. %R (return code) contains 1, the line number that was read. From our menu, we have started the IBM Macro Assembler program. We know that when this program ends, it will display a number representing the number of errors that were found. We want to make sure that this number is zero before continuing to the LINK program. If we save this number in the variable %A, what is the command to read the assembler result from the display? BAT READSCRN %A STATEOF command: Will search all disk drives for the existance of a file. --------------- The name after the word STATEOF can be a specific name, general name with wildcard characters (e.g. *.EXE), or it can be a name with a specific drive and extension, e.g. A:PE.EXE). In the last case, only drive A: will be searched instead of all available drives. Note also that a variable can be used instead of a file name. In this version of BAT, only files in the current directory (no paths) can be found. The return code variable %R is used to indicate the result of the search for STATEOF. The results are: 0 - File found on default drive. 1 - File not found. 9 - Invalid file name specified. A to D - Same as return code 0 but instead of being found on the default drive, it was found on drive A, B, C, or D. User programs may also set the return code in order to control the execution of the BAT batch file program, but this is most commonly done when using the command STATEOF to search for a file. If a file exists, we could direct a program to use it, even if it wasn't on the specific diskette drive that the operator was expecting. If the file was not there, we could have printed out an error message to the operator, or we could have run an alternate program in order to create the missing file. STATEOF command example: bat type Enter a filename for me to search for: bat read %9 bat type scanning for file: %9 . . . bat stateof %9 * this will search and set the return code up (%R) bat if %r <> 0 skip 2 bat type the file does exist - exactly as typed. bat skip 7 bat if %r <> 1 skip 2 bat type the file does not exist on any drive. bat skip 5 bat if %r <> 9 skip 2 bat type the file name given is invalid. bat skip 2 bat type the file does exist - but was found on the %r drive. bat type to properly find this file, the complete filename would be %9 ASSIGNMENTS: ----------- If the first character in the command is a '%' (Percent sign), then it is considered to be an assignment statement. The first variable cannot be any predefined variable (such as %R or %), but may be any of the other variables %0 to %9 and %A to %O. If a DOS command is later executed and uses one of the variables %0 to %9, it will be properly replaced with the contents of that variable. The first assignment token, the operator, and the final tokens are optional. The assignment statement must appear in one of the following forms: [var] = * create empty variable [var] = [string] * simple assignment [var] = [number] + [number] * addition [var] = [number] - [number] * subtraction [var] = [number] * [number] * multiplication [var] = [number] / [number] * division [var] = [string] # * string length [var] = [string] $ [index] [length] * create substring (like MID$ in BASIC) where: [var] is a DOS variable or global user variable %0 to %9 and %A to %O. It may not be a predefined variable. [string] is any valid token. Letters, numbers, any variable, or any combination. 123, ABC, and 987%J4SF are all valid strings. [number] is any token with a numeric result in the range of 0 to 65535. For example (if %A contains 34) the three numbers 98, %A, and 12%A5 (equivalent to 12345) would all be valid numbers. Note that numbers are always positive and should never contain a sign ( + or - ) character. [index] Same restrictions as [number] above except that an [index] in the range 17 to 65535 is meaningless and is equivalent to the number 16. [length]Same restrictions as [number] above except that a [length] in the range 16 to 65535 is meaningless and is equivalent to the number 15. Note that [length] is optional and has a default value of 15. ADDITIONAL INFO: There are additional variables %A thru %O (oh) which are called "global user variables". These variables are used exactly like the variables supplied by DOS (%0 to %9) with TWO EXCEPTIONS. 1) The contents of these variables are maintained between execution of batch files for as long as the system is powered on. This "global" feature is useful for keeping indicators BETWEEN "sessions" of the user. 2) Because DOS does not know about these variables, they CANNOT BE USED AS VARIABLES WITHIN ANY DOS COMMAND. So "COPY %1 %2" is valid, "COPY %A %B" is not. If you wish to use them within DOS commands, they must first be copied via a statement like "BAT %1 = %A". PREDEFINED VARIABLES... A return code is available at memory address [0000:04FE]. If set by a program, BAT can read this byte value with the variable %R. The string stored into this variable is in hex with leading zeros truncated. The current default drive is stored into the %V variable. It is a single character. The status of the stack is stored into the %Q variable. It is a "K" if the READ command will be reading from the keyboard, and a "S" if it will be reading from the stack area. There are two character literals. %S represents a space literal and %% represents a percent sign. Either of these special variables can be stored into other variables, or used for testing special cases. OTHER CONTROLS... If a you wish to put more than one command on a line, the vertical bar "|" is useful. When used with an IF command and the test for the IF conditions fail, the entire rest of the line will be ignored. Multiple commands within a BAT statement is very useful when combined with the IF command. For example: BAT IF %A = abc TYPE this | CALL -that | GOTO -other If a comment is needed within a BAT program, the "*" (star) character is useful. When used after the word BAT, all characters which follow will be ignored. For example: BAT * This is a comment to the programmer. MORE..... A BAT program can create loops and count events. With this you can sequence through file numbers, or create loops to do retrys in case of errors. In addition, BAT programs can do simple arithmetic and string manipulation. EXAMPLE: bat * number guessing demo * bat %7 = 30 bat %6 = 5 bat cls type I am thinking of a two digit number, can you guess it? bat -c.loop read %5 bat if %5 = %7 skip 7 bat %6 = %6 - 1 bat if %6 <> 0 skip 2 bat type boo hisss! the number was %7! bat skip 4 bat if %5 > %7 type try a little lower. you only get %6 more tries. bat if %5 < %7 type try a higher number. you get %6 more tries. bat goto -c.loop bat type great! i was afraid you weren't going to get it! In this example, a directory is displayed by using a DOS command within a batch file. ANY DOS COMMAND can be mixed freely within lines of the BAT program. bat cls bat * display a directory bat type Enter a file specification or just enter key for all: bat read %1 bat if .%1 = . %1 = *.* bat -dirques type Would you like a (S)tandard or (W)ide directory? bat inkey %2 | %m = %2 # | if %m = 1 type %2 bat * Notice you can chain togeather if's, like . . . bat if %2 <> s if %2 <> w goto -dirques * EQUIV OF AN `AND' FUNCTION bat %3 = bat if %2 = w %3 = /w bat cls DIR %1 %3 (notice that two parms are passed to dos here. %%1 and %%3) By passing parameters to/from DOS, you can have complete control of how a program operates. DEBUGGING --------- TRACE.ON command: ---------------- Enables a trace flag which causes each line in the BAT program to be printed as it is executed. Three '+' (plus) symbols will precede the BAT statement that is printed out. A trace can be active during DOS commands within the BAT program. In addition, trace can be enabled/disabled at any time, even in immediate mode. Once enabled, it will remain in effect until the TRACE.OFF command is executed. Errors, execution of other BAT language files, and even executing DOS commands will not change the trace mode. TRACE.OFF command: Disables trace ----------------- s type I am thinking of a two digit number, can you guess it? bat -c.loop read %5 bat if %5 = %7 skip 7 bat %6 = %6